home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / general / hdf / docs / hdfvset.lha / HDFVset.ch4 < prev    next >
Text File  |  1994-01-10  |  6KB  |  287 lines
  1. 4.2    NCSA HDF Vset
  2.  
  3.  
  4. Vgroup Routine Descriptions    4.1
  5.  
  6.  
  7. National Center for Supercomputing Applications
  8.  
  9. November 1990
  10.  
  11.                                                                 
  12.  
  13.  
  14.  
  15.  
  16.  
  17. 4.1    NCSA HDF Vset
  18.  
  19. Vgroup Routine Descriptions    4.1
  20.  
  21. National Center for Supercomputing Applications
  22.  
  23. November 1990
  24.  
  25.                                                                 
  26.  
  27. March 1990
  28.  
  29.  
  30.  
  31.  
  32. Chapter  4    Vgroup Routine Descriptions
  33.  
  34.  
  35.  
  36. Chapter Overview
  37. Vattach
  38. Vdetach
  39. Vgetclass
  40. Vgetid
  41. Vgetname
  42. Vgetnext
  43. Vinquire
  44. Vinsert
  45. Visvg
  46. Visvs
  47. Vlone
  48. Vsetclass
  49. Vsetname
  50.  
  51. Chapter Overview
  52.  
  53. This chapter describes the vgroup routines in the C library in 
  54. detail.
  55.  
  56. Vattach
  57. (VGROUP*) Vattach   ( f, vgid, access)
  58.  
  59.     DF    *f;
  60.     int    vgid;
  61.     char    *access;     [either "r" or "w"] 
  62.  
  63. Purpose:  This access routine attachs to a vgroup having id vgid, 
  64. and then returns a pointer to that group. 
  65.  
  66. Specifics:
  67.  
  68.     f is a pointer to an opened HDF file.
  69.     vgid specifies which vgroup in the HDF file to attach to:
  70.  
  71.     Ñ    if vgid = -1, a new vgroup is created.
  72.  
  73.     Ñ    if vgid is +ve, the vgroup corresponding to the vgid is 
  74.             attached.
  75.  
  76. (The access argument currently is not used; all vgroups are 
  77. attached with both read and write access.)
  78.  
  79. Return value:  Upon a successful attach, a vgroup pointer is 
  80. returned. Otherwise, NULL is returned.
  81.  
  82.  
  83. Vdetach
  84. (void) Vdetach   (vg)
  85.  
  86.     VGROUP    *vg;
  87.  
  88.  
  89. Purpose:  This access routine detaches vg, the vgroup that was 
  90. currently attached, terminating further access to that vgroup.
  91.  
  92. Specifics:  All space associated with that vgroup will be freed. All 
  93. vgroups should be detached using this routine before closing the 
  94. file. Vdetach also updates the vgroup information in the HDF file 
  95. if any changes occur.
  96.  
  97. Return value:  None.
  98.  
  99.  
  100. Vgetclass
  101. (void) Vgetclass   (vg,vgclass)
  102.  
  103.     VDATA        *vs;
  104.     char        *vsclass;
  105.  
  106. Purpose:  This specify routine returns, in the variable vgclass, the 
  107. class field name (if any) of the vdata vg. 
  108.  
  109. Return value:  None.
  110.  
  111.  
  112. Vgetid
  113. int Vgetid   (f, vgid)
  114.  
  115.     DF    *f;
  116.     int    vgid;
  117.  
  118. Purpose:  This search routine searches through the HDF file and 
  119. returns the id of the next VGROUP following the vgroup that has id 
  120. vgid.
  121.  
  122. Specifics:  To initiate a search, call this routine with a value of -1 
  123. for vgid. This will return the id of the first vdata in the file.
  124.  
  125. Return value:  Upon success, the id (0 or the integer) of the next 
  126. vdata is returned; on error, or when there are no more vgroups, -1 
  127. is returned.
  128.  
  129.  
  130. Vgetname
  131. (void) Vgetname   (vg, vgname)
  132.  
  133.     VGROUP    *vg;
  134.     char    *vgname;
  135.  
  136. Purpose:  This inquiry routine returns, in the variable vgname, the 
  137. name of the vgroup vg.
  138.  
  139. Return value:  None.
  140.  
  141.  
  142. Vgetnext
  143. int Vgetnext   (vg, id)
  144.  
  145.     VGROUP    *vg;
  146.     int    id;
  147.  
  148. Purpose:  This search routine is used to sequence through a vgroup.  
  149. It searches the vgroup vg and returns the id of the next entity 
  150. (vgroup or vdata) after the entity that has id, id.
  151.  
  152. Specifics:  Note that the entity may be either a vdata or another 
  153. vgroup. To initiate a search, call this routine with -1 as argument 
  154. for id. This action will return the id of the first entity  in vg.
  155.  
  156. Return value:  Upon success, the id of the vgroup or vdata is 
  157. returned. If there is an error, or when there are no more entities in 
  158. that vgroup, -1 is returned.
  159.  
  160.  
  161. Vinquire
  162. Vinquire   (vs, nentries, vgname)
  163.  
  164.     VGROUP    *vg;
  165.     char    *vgname;
  166.     int    *nentries;
  167.  
  168. Purpose:  This is the general vgroup inquiry routine.
  169.  
  170. Specifics:  Given a vgroup vg, Vinquire returns the following:
  171.  
  172.     Ñnentries    the number of entries (i.e., the total number 
  173.         of vgroups and vdatas) in this vgroup.
  174.  
  175.     Ñvgname    the name (if any) of the vgroup. Otherwise, 
  176.         NULL is returned.
  177.  
  178. Return value:  Upon success, 1 is returned; otherwise, -1.
  179.  
  180.  
  181. Vinsert
  182. int Vinsert   (vg, v)    
  183.     
  184.     VGROUP    *vg;
  185.     VDATA    *v;    [or    VGROUP    *v;]
  186.     int    n;
  187.  
  188. Purpose:  This linkage routine establishes a link from the vgroup 
  189. vg to either another vgroup or to a vdata v.
  190.  
  191. Specifics:  Essentially, Vinsert allows vgroups or vdatas to belong 
  192. to a vgroup. The routine does not check for any cycles that may 
  193. result.
  194.  
  195. Return value:  Upon success, the position of the inserted entity 
  196. (vgroup or vdata) within the vgroup vg is returned (0 or a +ve 
  197. integer); upon error, -1.
  198.  
  199.  
  200. Visvg
  201. int Visvg   (vg, id)
  202.  
  203.     VGROUP    *vg;
  204.     int    id;
  205.  
  206. Purpose:  This inquiry routine tests whether an entity (vgroup or 
  207. vdata) having id, id in a vgroup vg is a vgroup. Id is any valid id 
  208. returned by Vgetnext.
  209.  
  210. Return value:  If id indeed refers to a vgroup within the vgroup vg, 
  211. 1 is returned; otherwise, 0 is returned.
  212.  
  213.  
  214. Visvs
  215. int Visvs   (vg, id)
  216.  
  217.     VGROUP    *vg;
  218.     int        id;
  219.  
  220. Purpose:  This inquiry routine tests whether an entity (vgroup or 
  221. vdata) having id, id in a vgroup vg is a vdata. Id  is any valid id 
  222. returned by VSgetnext.
  223.  
  224. Return value:  If id indeed refers to a vdata within the vgroup vg, 1 
  225. is returned; otherwise 0 is returned.
  226.  
  227.  
  228. Vlone
  229. int Vlone   (f, idarray, asize)
  230.  
  231.     DF        *f;
  232.     int        idarray [];
  233.     int        asize;
  234.  
  235. Purpose:  This inquiry routine returns an array of reference 
  236. numbers of all vgroups that are not linked to any vgroup in the 
  237. HDF file.
  238.  
  239. Specifics:  You must provide the integer array idarray, and you 
  240. must specify the integer size of the array in the argument asize. 
  241. The return value from this function will be the total number of 
  242. VGROUPS that are not linked to any vgroup in the file. But at most 
  243. asize reference numbers will be returned in idarray.
  244.  
  245. An array size of 65000 integers for idarray will be usually more 
  246. than adequate. To use dynamic memory instead, first call Vlone 
  247. with a small value (e.g. 0 or 1) for asize, and then use the returned 
  248. value to allocate memory for idarray to be passed to a subsequent 
  249. call to Vlone.
  250.  
  251. Return value:  If there is an error, the return value is -1.  
  252. Otherwise, it returns the total number of all vgroups in the file that 
  253. are not linked to any vgroup.
  254.  
  255.  
  256. Vsetclass
  257. (void) Vsetclass   (vg,vgclass)
  258.  
  259.     VGROUP        *vg;
  260.     char        *vgclass;
  261.  
  262. Purpose:  This specify routine associates the class fieldname 
  263. vgclass with the vdata vg.
  264.  
  265. Specifics:  Vgroups initially have a class name of NULL. The 
  266. class name may be set more than once.
  267.  
  268. Return value:  None.
  269.  
  270.  
  271. Vsetname 
  272. (void) Vsetname   (vg, vgname)
  273.  
  274.     VGROUP    *vg;
  275.     char    *vgname;    
  276.  
  277. Purpose:  This specify routine associates the vgroup vg with the 
  278. name vgname.
  279.  
  280. Specifics:  Vgroups each initially have a vgname of NULL, and 
  281. may be renamed more than once. Note that the routine does NOT 
  282. check for uniqueness of vgroup names.
  283.  
  284. Return values:  None.
  285.  
  286.  
  287.